<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<link rel="shortcut icon" type="image/x-icon" href="favicon.ico"/>
<title>DynamoRIO API: dr_inject.h File Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">DynamoRIO API
   </div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.1.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('dr__inject_8h.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="summary">
<a href="#define-members">Macros</a> &#124;
<a href="#func-members">Functions</a>  </div>
  <div class="headertitle">
<div class="title">dr_inject.h File Reference</div>  </div>
</div><!--header-->
<div class="contents">

<p>Injection API. Use these functions to launch processes under the control of DynamoRIO.  
<a href="#details">More...</a></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2><a name="define-members"></a>
Macros</h2></td></tr>
<tr class="memitem:a59d7d07c8ff5002b85b45d7ac21bdd51"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="dr__inject_8h.html#a59d7d07c8ff5002b85b45d7ac21bdd51">ERROR_IMAGE_MACHINE_TYPE_MISMATCH_EXE</a>&#160;&#160;&#160;720L</td></tr>
<tr class="memitem:a7e904aca534e09fccc4502dcc9ca5193"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="dr__inject_8h.html#a7e904aca534e09fccc4502dcc9ca5193">WARN_IMAGE_MACHINE_TYPE_MISMATCH_EXE</a>&#160;&#160;&#160;<a class="el" href="dr__inject_8h.html#a59d7d07c8ff5002b85b45d7ac21bdd51">ERROR_IMAGE_MACHINE_TYPE_MISMATCH_EXE</a></td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:a77b0c082257a96deebb67ad23f381426"><td class="memItemLeft" align="right" valign="top">DR_EXPORT int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="dr__inject_8h.html#a77b0c082257a96deebb67ad23f381426">dr_inject_process_create</a> (const char *app_name, const char **app_cmdline, void **data)</td></tr>
<tr class="memitem:a4acf52ec4bc354ad729dd7e580e5ffb0"><td class="memItemLeft" align="right" valign="top">DR_EXPORT int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="dr__inject_8h.html#a4acf52ec4bc354ad729dd7e580e5ffb0">dr_inject_prepare_to_exec</a> (const char *app_name, const char **app_cmdline, void **data)</td></tr>
<tr class="memitem:aac318714936b1f01498cd28f4718d0fc"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="dr__inject_8h.html#aac318714936b1f01498cd28f4718d0fc">dr_inject_prepare_to_ptrace</a> (void *data)</td></tr>
<tr class="memitem:a6c45ee5291880dce2c26e06233c02a03"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="dr__inject_8h.html#a6c45ee5291880dce2c26e06233c02a03">dr_inject_prepare_new_process_group</a> (void *data)</td></tr>
<tr class="memitem:ab2a383d92917deebddd8c5ce2d80ea12"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="dr__inject_8h.html#ab2a383d92917deebddd8c5ce2d80ea12">dr_inject_process_inject</a> (void *data, bool force_injection, const char *library_path)</td></tr>
<tr class="memitem:a2cb96f6575ec364703c228667a9cc2be"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="dr__inject_8h.html#a2cb96f6575ec364703c228667a9cc2be">dr_inject_process_run</a> (void *data)</td></tr>
<tr class="memitem:afe7492fc543a3e395af4c6de7846ee43"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="dr__inject_8h.html#afe7492fc543a3e395af4c6de7846ee43">dr_inject_wait_for_child</a> (void *data, uint64 timeout_millis)</td></tr>
<tr class="memitem:afdd617e9fd2f5876fdaa63c27839c6de"><td class="memItemLeft" align="right" valign="top">DR_EXPORT int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="dr__inject_8h.html#afdd617e9fd2f5876fdaa63c27839c6de">dr_inject_process_exit</a> (void *data, bool terminate)</td></tr>
<tr class="memitem:aac52fbcd5daed793a91a7903f393086f"><td class="memItemLeft" align="right" valign="top">DR_EXPORT char *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="dr__inject_8h.html#aac52fbcd5daed793a91a7903f393086f">dr_inject_get_image_name</a> (void *data)</td></tr>
<tr class="memitem:ac93f0d554f2ae003ba97e3aa5815eb2a"><td class="memItemLeft" align="right" valign="top">DR_EXPORT HANDLE&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="dr__inject_8h.html#ac93f0d554f2ae003ba97e3aa5815eb2a">dr_inject_get_process_handle</a> (void *data)</td></tr>
<tr class="memitem:a953a5604db5cb8570b063b6a95764044"><td class="memItemLeft" align="right" valign="top">DR_EXPORT process_id_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="dr__inject_8h.html#a953a5604db5cb8570b063b6a95764044">dr_inject_get_process_id</a> (void *data)</td></tr>
<tr class="memitem:ade6be04e498ae27d72d15b00314ed230"><td class="memItemLeft" align="right" valign="top">DR_EXPORT void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="dr__inject_8h.html#ade6be04e498ae27d72d15b00314ed230">dr_inject_print_stats</a> (void *data, int elapsed_secs, bool showstats, bool showmem)</td></tr>
</table>
<hr/><a name="details" id="details"></a><h2>Detailed Description</h2>
<div class="textblock"><p>Injection API. Use these functions to launch processes under the control of DynamoRIO. </p>
</div><hr/><h2>Macro Definition Documentation</h2>
<a class="anchor" id="a59d7d07c8ff5002b85b45d7ac21bdd51"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">#define ERROR_IMAGE_MACHINE_TYPE_MISMATCH_EXE&#160;&#160;&#160;720L</td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Special error code that is returned by <code>dr_inject_prepare_to_exec</code> or <code>dr_inject_process_create</code> when the target application image does not match the bitwidth of the injection front-end. The target process is still created: it is up to the caller to decide whether to abort (and if so, it should call <a class="el" href="dr__inject_8h.html#afdd617e9fd2f5876fdaa63c27839c6de">dr_inject_process_exit()</a>), although on Windows this is generally a fatal error with the current implementation. We use ERROR_IMAGE_MACHINE_TYPE_MISMATCH_EXE in both Windows and Unix assuming no error code conflict on Unix. </p>

</div>
</div>
<a class="anchor" id="a7e904aca534e09fccc4502dcc9ca5193"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">#define WARN_IMAGE_MACHINE_TYPE_MISMATCH_EXE&#160;&#160;&#160;<a class="el" href="dr__inject_8h.html#a59d7d07c8ff5002b85b45d7ac21bdd51">ERROR_IMAGE_MACHINE_TYPE_MISMATCH_EXE</a></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Alias of ERROR_IMAGE_MACHINE_TYPE_MISMATCH_EXE to indicate it is not a fatal error on Unix. </p>

</div>
</div>
<hr/><h2>Function Documentation</h2>
<a class="anchor" id="aac52fbcd5daed793a91a7903f393086f"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT char* dr_inject_get_image_name </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>data</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Returns the process name of a process created by <a class="el" href="dr__inject_8h.html#a77b0c082257a96deebb67ad23f381426">dr_inject_process_create()</a>.</p>
<dl class="params"><dt>Parameters:</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">data</td><td>The pointer returned by <a class="el" href="dr__inject_8h.html#a77b0c082257a96deebb67ad23f381426">dr_inject_process_create()</a></td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns:</dt><dd>Returns the process name of the process. This is the file name without the path, suitable for passing to <a class="el" href="dr__config_8h.html#a10d7c5dbc9a055fa6c18bf3f2a6eea46">dr_register_process()</a>. </dd></dl>

</div>
</div>
<a class="anchor" id="ac93f0d554f2ae003ba97e3aa5815eb2a"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT HANDLE dr_inject_get_process_handle </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>data</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Returns a handle to a process created by <a class="el" href="dr__inject_8h.html#a77b0c082257a96deebb67ad23f381426">dr_inject_process_create()</a>.</p>
<dl class="params"><dt>Parameters:</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">data</td><td>The pointer returned by <a class="el" href="dr__inject_8h.html#a77b0c082257a96deebb67ad23f381426">dr_inject_process_create()</a></td></tr>
  </table>
  </dd>
</dl>
<dl class="section note"><dt>Note:</dt><dd>Windows only.</dd></dl>
<dl class="section return"><dt>Returns:</dt><dd>Returns the handle used by drinjectlib. Do not close the handle: it will be closed in <a class="el" href="dr__inject_8h.html#afdd617e9fd2f5876fdaa63c27839c6de">dr_inject_process_exit()</a>. </dd></dl>

</div>
</div>
<a class="anchor" id="a953a5604db5cb8570b063b6a95764044"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT process_id_t dr_inject_get_process_id </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>data</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Returns the pid of a process created by <a class="el" href="dr__inject_8h.html#a77b0c082257a96deebb67ad23f381426">dr_inject_process_create()</a>.</p>
<dl class="params"><dt>Parameters:</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">data</td><td>The pointer returned by <a class="el" href="dr__inject_8h.html#a77b0c082257a96deebb67ad23f381426">dr_inject_process_create()</a></td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns:</dt><dd>Returns the pid of the process. </dd></dl>

</div>
</div>
<a class="anchor" id="a6c45ee5291880dce2c26e06233c02a03"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">bool dr_inject_prepare_new_process_group </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>data</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Put the child in a new process group. If termination is requested with <a class="el" href="dr__inject_8h.html#afdd617e9fd2f5876fdaa63c27839c6de">dr_inject_process_exit()</a>, the entire child process group is killed. Using this option creates a new process group, so if the process group of the injector is killed, the child will survive, which may not be desirable. This routine only operates on child process, and will fail if <a class="el" href="dr__inject_8h.html#a4acf52ec4bc354ad729dd7e580e5ffb0">dr_inject_prepare_to_exec()</a> has been called instead of <a class="el" href="dr__inject_8h.html#a77b0c082257a96deebb67ad23f381426">dr_inject_process_create()</a>.</p>
<dl class="section note"><dt>Note:</dt><dd>Only available on Linux.</dd></dl>
<dl class="params"><dt>Parameters:</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">data</td><td>The pointer returned by <a class="el" href="dr__inject_8h.html#a77b0c082257a96deebb67ad23f381426">dr_inject_process_create()</a> </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<a class="anchor" id="a4acf52ec4bc354ad729dd7e580e5ffb0"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT int dr_inject_prepare_to_exec </td>
          <td>(</td>
          <td class="paramtype">const char *&#160;</td>
          <td class="paramname"><em>app_name</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const char **&#160;</td>
          <td class="paramname"><em>app_cmdline</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">void **&#160;</td>
          <td class="paramname"><em>data</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Prepare to exec() the provided command from the current process. Use <a class="el" href="dr__inject_8h.html#ab2a383d92917deebddd8c5ce2d80ea12">dr_inject_process_inject()</a> to perform the exec() under DR.</p>
<dl class="section note"><dt>Note:</dt><dd>Only available on Linux.</dd></dl>
<dl class="params"><dt>Parameters:</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">app_name</td><td>The path to the target executable. The caller must ensure this data is valid until the inject data is disposed.</td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">app_cmdline</td><td>A NULL-terminated array of strings representing the app's command line. This should match what the app will receive as <code>argv</code> in main(). The caller must ensure this data is valid until the inject data is disposed.</td></tr>
    <tr><td class="paramdir">[out]</td><td class="paramname">data</td><td>An opaque pointer that should be passed to subsequent dr_inject_* routines to refer to this process. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns:</dt><dd>Returns 0 on success. On failure, returns a system error code. For a mismatched bitwidth, the code is ERROR_IMAGE_MACHINE_TYPE_MISMATCH_EXE. On returning ERROR_IMAGE_MACHINE_TYPE_MISMATCH_EXE on Unix, <code>data</code> will be initialized: i.e., it is merely a warning, and the caller may continue with cross arch injection. Regardless of success, caller must call <a class="el" href="dr__inject_8h.html#afdd617e9fd2f5876fdaa63c27839c6de">dr_inject_process_exit()</a> when finished to clean up internally-allocated resources. </dd></dl>

</div>
</div>
<a class="anchor" id="aac318714936b1f01498cd28f4718d0fc"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool dr_inject_prepare_to_ptrace </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>data</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Use the ptrace system call to inject into the targetted process. Must be called before <a class="el" href="dr__inject_8h.html#ab2a383d92917deebddd8c5ce2d80ea12">dr_inject_process_inject()</a>. Does not work with <a class="el" href="dr__inject_8h.html#a4acf52ec4bc354ad729dd7e580e5ffb0">dr_inject_prepare_to_exec()</a>.</p>
<p>Newer Linux distributions restrict which processes can be ptraced. If DR fails to attach, make sure that gdb can attach to the process in question.</p>
<p>Once in the injectee, DynamoRIO searches the $HOME directory of the user of the injector, not the user of the injectee. Normal usage of drconfig and drinjectlib will ensure that DynamoRIO finds the right config files, however users that wish to examine config files need to check the home directory of the injector's user.</p>
<dl class="section warning"><dt>Warning:</dt><dd>ptrace injection is still experimental and subject to change.</dd></dl>
<dl class="params"><dt>Parameters:</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">data</td><td>The pointer returned by <a class="el" href="dr__inject_8h.html#a77b0c082257a96deebb67ad23f381426">dr_inject_process_create()</a></td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns:</dt><dd>Whether successful. </dd></dl>

</div>
</div>
<a class="anchor" id="ade6be04e498ae27d72d15b00314ed230"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT void dr_inject_print_stats </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>data</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">int&#160;</td>
          <td class="paramname"><em>elapsed_secs</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">bool&#160;</td>
          <td class="paramname"><em>showstats</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">bool&#160;</td>
          <td class="paramname"><em>showmem</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Prints statistics for a process created by <a class="el" href="dr__inject_8h.html#a77b0c082257a96deebb67ad23f381426">dr_inject_process_create()</a>.</p>
<dl class="params"><dt>Parameters:</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">data</td><td>The pointer returned by <a class="el" href="dr__inject_8h.html#a77b0c082257a96deebb67ad23f381426">dr_inject_process_create()</a></td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">elapsed_secs</td><td>Elapsed time recorded by the caller that will be printed by this routine if showstats is true.</td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">showstats</td><td>If true, elapsed_secs and resource usage is printed.</td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">showmem</td><td>If true, memory usage statistics are printed. </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<a class="anchor" id="a77b0c082257a96deebb67ad23f381426"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT int dr_inject_process_create </td>
          <td>(</td>
          <td class="paramtype">const char *&#160;</td>
          <td class="paramname"><em>app_name</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const char **&#160;</td>
          <td class="paramname"><em>app_cmdline</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">void **&#160;</td>
          <td class="paramname"><em>data</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Creates a new process for the executable and command line specified. The initial thread in the process is suspended. Use <a class="el" href="dr__inject_8h.html#ab2a383d92917deebddd8c5ce2d80ea12">dr_inject_process_inject()</a> to inject DynamoRIO into the process (first calling <a class="el" href="dr__config_8h.html#a10d7c5dbc9a055fa6c18bf3f2a6eea46">dr_register_process()</a> to configure the process, for one-time targeted configuration), <a class="el" href="dr__inject_8h.html#a2cb96f6575ec364703c228667a9cc2be">dr_inject_process_run()</a> to resume the thread, and <a class="el" href="dr__inject_8h.html#afdd617e9fd2f5876fdaa63c27839c6de">dr_inject_process_exit()</a> to finish and free resources.</p>
<dl class="params"><dt>Parameters:</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">app_name</td><td>The path to the target executable. The caller must ensure this data is valid until the inject data is disposed.</td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">app_cmdline</td><td>A NULL-terminated array of strings representing the app's command line. This should match what the app will receive as <code>argv</code> in main(). The caller must ensure this data is valid until the inject data is disposed.</td></tr>
    <tr><td class="paramdir">[out]</td><td class="paramname">data</td><td>An opaque pointer that should be passed to subsequent dr_inject_* routines to refer to this process. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns:</dt><dd>Returns 0 on success. On failure, returns a system error code. For a mismatched bitwidth, the code is ERROR_IMAGE_MACHINE_TYPE_MISMATCH_EXE. On returning ERROR_IMAGE_MACHINE_TYPE_MISMATCH_EXE on Unix, <code>data</code> will be initialized and child process created: i.e., it is merely a warning, and the caller may continue with cross arch injection. Regardless of success, caller must call <a class="el" href="dr__inject_8h.html#afdd617e9fd2f5876fdaa63c27839c6de">dr_inject_process_exit()</a> when finished to clean up internally-allocated resources. </dd></dl>

</div>
</div>
<a class="anchor" id="afdd617e9fd2f5876fdaa63c27839c6de"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT int dr_inject_process_exit </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>data</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">bool&#160;</td>
          <td class="paramname"><em>terminate</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Frees resources used by <a class="el" href="dr__inject_8h.html#a77b0c082257a96deebb67ad23f381426">dr_inject_process_create()</a>. Does not wait for the child to exit, unless terminate is true.</p>
<dl class="params"><dt>Parameters:</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">data</td><td>The pointer returned by <a class="el" href="dr__inject_8h.html#a77b0c082257a96deebb67ad23f381426">dr_inject_process_create()</a></td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">terminate</td><td>If true, the process is forcibly terminated.</td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns:</dt><dd>Returns the exit code of the process. If the caller did not wait for the process to finish before calling this, the code will be STILL_ACTIVE. </dd></dl>

</div>
</div>
<a class="anchor" id="ab2a383d92917deebddd8c5ce2d80ea12"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool dr_inject_process_inject </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>data</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">bool&#160;</td>
          <td class="paramname"><em>force_injection</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const char *&#160;</td>
          <td class="paramname"><em>library_path</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Injects DynamoRIO into a process created by <a class="el" href="dr__inject_8h.html#a77b0c082257a96deebb67ad23f381426">dr_inject_process_create()</a>, or the current process if using <a class="el" href="dr__inject_8h.html#a4acf52ec4bc354ad729dd7e580e5ffb0">dr_inject_prepare_to_exec()</a> on Linux.</p>
<dl class="params"><dt>Parameters:</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">data</td><td>The pointer returned by <a class="el" href="dr__inject_8h.html#a77b0c082257a96deebb67ad23f381426">dr_inject_process_create()</a></td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">force_injection</td><td>Requests injection even if the process is configured to not be run under DynamoRIO.</td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">library_path</td><td>The path to the DynamoRIO library to use. If NULL, the library that the target process is configured for will be used.</td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns:</dt><dd>Whether successful. </dd></dl>

</div>
</div>
<a class="anchor" id="a2cb96f6575ec364703c228667a9cc2be"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool dr_inject_process_run </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>data</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Resumes the suspended thread in a process created by <a class="el" href="dr__inject_8h.html#a77b0c082257a96deebb67ad23f381426">dr_inject_process_create()</a>.</p>
<dl class="params"><dt>Parameters:</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">data</td><td>The pointer returned by <a class="el" href="dr__inject_8h.html#a77b0c082257a96deebb67ad23f381426">dr_inject_process_create()</a></td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns:</dt><dd>Whether successful. </dd></dl>

</div>
</div>
<a class="anchor" id="afe7492fc543a3e395af4c6de7846ee43"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool dr_inject_wait_for_child </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>data</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">uint64&#160;</td>
          <td class="paramname"><em>timeout_millis</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Waits for the child process to exit with the given timeout.</p>
<dl class="params"><dt>Parameters:</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">data</td><td>The pointer returned by <a class="el" href="dr__inject_8h.html#a77b0c082257a96deebb67ad23f381426">dr_inject_process_create()</a> </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">timeout_millis</td><td>The timeout in milliseconds. Zero means wait forever.</td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns:</dt><dd>Return true if the child exited, and false if we timed out.</dd></dl>
<dl class="section note"><dt>Note:</dt><dd>On Linux, this sets a signal handler for SIGALRM. </dd></dl>

</div>
</div>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="navelem"><a class="el" href="dir_3f960cec7fb648840e8ab2c814e874ae.html">include</a></li><li class="navelem"><a class="el" href="dr__inject_8h.html">dr_inject.h</a></li>
    <li class="footer" style="float:none;text-align:center"><img border=0 src="favicon.png"> &nbsp;  DynamoRIO API version 5.0.0 --- Wed Sep 10 2014 21:36:43 &nbsp; <img border=0 src="favicon.png">
</small></address>
<!--END !GENERATE_TREEVIEW-->
</body>
</html>
